home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d18
/
tphrt3.arc
/
TPHRTV3.DOC
< prev
next >
Wrap
Text File
|
1990-07-23
|
77KB
|
2,176 lines
TPHRT
Turbo Pascal High Resolution Timer Toolbox
Version 3.00
Shareware Evaluation Version
Ryle Design
P.O. Box 22
Mt. Pleasant, Michigan 48804
(517) 773-0587
Cserv 73047,1765
Contents
TPHRT User Guide 1
Introduction . . . . . . . . . . . . . . . . . . . . . 1
Functional Overview . . . . . . . . . . . . . . . . . . 2
Theory . . . . . . . . . . . . . . . . . . . . . . . . 3
TPHRT Function Descriptions . . . . . . . . . . . . . . 4
Examples . . . . . . . . . . . . . . . . . . . . . . . 8
Technical Support . . . . . . . . . . . . . . . . . . . 8
Shareware . . . . . . . . . . . . . . . . . . . . . . . 8
TPHRT Function Reference 11
t_ask_delay . . . . . . . . . . . . . . . . . . . . . 11
t_ask_timer . . . . . . . . . . . . . . . . . . . . . 11
t_bios_ask . . . . . . . . . . . . . . . . . . . . . 12
t_bios_entry . . . . . . . . . . . . . . . . . . . . 12
t_bios_exit . . . . . . . . . . . . . . . . . . . . . 13
t_bios_fname . . . . . . . . . . . . . . . . . . . . 13
t_bios_load_desc . . . . . . . . . . . . . . . . . . 13
t_bios_report . . . . . . . . . . . . . . . . . . . . 14
t_bios_resume . . . . . . . . . . . . . . . . . . . . 14
t_bios_reset . . . . . . . . . . . . . . . . . . . . 15
t_bios_rname . . . . . . . . . . . . . . . . . . . . 15
t_bios_set_file . . . . . . . . . . . . . . . . . . . 15
t_bios_set_user . . . . . . . . . . . . . . . . . . . 16
t_bios_start . . . . . . . . . . . . . . . . . . . . 16
t_bios_stop . . . . . . . . . . . . . . . . . . . . . 17
t_bios_suspend . . . . . . . . . . . . . . . . . . . 18
t_calc_delay_ff . . . . . . . . . . . . . . . . . . . 18
t_calib . . . . . . . . . . . . . . . . . . . . . . . 18
t_cvt_time . . . . . . . . . . . . . . . . . . . . . 19
t_delay_calib . . . . . . . . . . . . . . . . . . . . 19
t_diff . . . . . . . . . . . . . . . . . . . . . . . 20
t_do_delay . . . . . . . . . . . . . . . . . . . . . 20
t_do_delay_wints . . . . . . . . . . . . . . . . . . 20
t_entry . . . . . . . . . . . . . . . . . . . . . . . 21
t_exit . . . . . . . . . . . . . . . . . . . . . . . 21
t_fname . . . . . . . . . . . . . . . . . . . . . . . 22
t_get . . . . . . . . . . . . . . . . . . . . . . . . 22
t_get_delay_ff . . . . . . . . . . . . . . . . . . . 22
t_hires_entry . . . . . . . . . . . . . . . . . . . . 23
t_hires_exit . . . . . . . . . . . . . . . . . . . . 23
t_hook_int . . . . . . . . . . . . . . . . . . . . . 23
t_min_delay . . . . . . . . . . . . . . . . . . . . . 24
t_name . . . . . . . . . . . . . . . . . . . . . . . 24
t_report . . . . . . . . . . . . . . . . . . . . . . 24
t_request . . . . . . . . . . . . . . . . . . . . . . 25
t_res_delay . . . . . . . . . . . . . . . . . . . . . 25
t_reset . . . . . . . . . . . . . . . . . . . . . . . 25
i
t_resume . . . . . . . . . . . . . . . . . . . . . . 26
t_rname . . . . . . . . . . . . . . . . . . . . . . . 26
t_set_delay_ff . . . . . . . . . . . . . . . . . . . 26
t_setmode . . . . . . . . . . . . . . . . . . . . . . 27
t_start . . . . . . . . . . . . . . . . . . . . . . . 27
t_stop . . . . . . . . . . . . . . . . . . . . . . . 28
t_suspend . . . . . . . . . . . . . . . . . . . . . . 28
t_unhook_int . . . . . . . . . . . . . . . . . . . . 28
TPHRT V3.00 Registration . . . . . . . . . . . . . . . . 30
ii
TPHRT User Guide
Introduction
TPHRT (Turbo Pascal High Resolution Timer) is a software library that
provides the software developer with reliable timing functions that
work across the entire Intel 80xxx PC compatible hardware environment
with microsecond resolution. The TPHRT timing logic calibrates itself
to the host PC clock rate and processor environment at run-time, so a
single executable program will yield accurate results regardless of
the host microprocessor and clock speed.
TPHRT is the definitive choice for any PC application that requires
precision timing. Some typical TPHRT applications are:
Source Code Timer/Profiler
By adding timer calls to source code under development, TPHRT can
generate a detailed summary of execution time by program subroutine
and immediately illustrate the software's "hot spots" that might
benefit from further code or algorithm optimization. Unlike "binning"
profilers that display the number of "hits" in a range of program
addresses, TPHRT provides a direct one to one correspondence between
source code and elapsed time with user defined granularity.
Hardware Performance Evaluator
The high resolution and self calibration features of TPHRT make it
ideal for insertion in code to evaluate hardware performance. Disk
drives, numeric processors and CRT controllers can all have their
throughput measured very accurately with TPHRT, and with numerous
timers at the users disposal, many device functions may be
independently measured in a single run. The formatted timer report
generated by TPHRT makes compilation and interpretation of test
results painless.
Process Control
With TPHRT, process control applications that require precise timings
or precision delays are easy to implement. No longer will the
application developer have to make an educated guess as to how long a
critical interrupt is taking to service an I/O port as TPHRT can time
virtually any hardware or software interrupt and provide the developer
with precise accurate timings of the critical procedure. The
precision delay functions allow the programmer to implement data
acquisition loops with microsecond resolution.
Timing and Scoring
TPHRT is the perfect "timer engine" to build a timing and scoring
system for use in nearly any competitive event. With its microsecond
resolution and self calibration features, TPHRT surpasses conventional
sports timing equipment resolution and allows the application
developer to package high resolution timing and complete scoring
functionality in a single package.
Library Source Code Included
Since the source code to the TPHRT linkable libraries is included,
users needing a particular timing function not implemented can modify
the TPHRT functions to suit their particular requirements.
Functional Overview
The functionality of TPHRT can be divided into several distinct
categories of timer services:
TPHRT Timer Logic
These functions initialize the TPHRT timing system, calibrate the
timing logic, provide a low level interface to the PC timing hardware,
and perform miscellaneous timing functions that are generally hidden
from the user. Some of these functions will be of interest to users
who need to design their own timer functions and want to build on the
TPHRT low level timer logic.
Generic Timer Functions
These functions allow the user to control arbitrary event timers.
Functions exist to start, stop, suspend, resume, name, get elapsed
time and activation counts, and to generate detailed reports that
summarize all timer activity. Timer reports may be output to the
display, a disk file, or to the printer. A setmode function allows
users to run timers with interrupts enabled or disabled. The number
of timers active concurrently is restricted only by available memory.
BIOS Interrupt Timer Functions
These functions are similar to the Generic Timer Functions, but
operate only on BIOS interrupts. Using these functions the user may
install timer logic in any PC interrupt vector, and complete
information on that interrupt's activity can be generated. Interrupt
timer reports list interrupt activity broken down by interrupt
function (contents of the AH register when the interrupt is invoked)
and text files containing interrupt function descriptions may be
loaded to describe each interrupt function timer in the BIOS timer
report. Interrupt description files are provided for important
software interrupts in the PC/MSDOS environment. Multiple interrupts
may be timed concurrently.
Precision Delay Functions
These functions allow the user to generate delays with microsecond
accuracy. Functions exist to generate delays, query the delay logic
for available delay resolution and minimum delay time possible (these
are hardware dependent), and to "fine tune" the delay calibration for
one or more specific delay lengths.
TPHRT 2
Theory
TPHRT works by directly interfacing with channel 0 of the 8253 timer
chip found in all compatible PCs. Channel 0 counts from 65535 to 0,
when it triggers BIOS interrupt 8 and begins counting from 65535
again. Interrupt 8 is the hardware timer interrupt, and it increments
the DOS time of day data word in the BIOS data area, checks for
diskette motor activity and shuts down the motor if needed, and
finally calls BIOS interrupt 1C (hex), which is known as the software
timer tick. At boot time, 1C contains an IRET instruction, meaning
there is no routine installed in that vector. Since the 8253 has a
period of 838 nanoseconds, the hardware timer tick occurs every 54.925
milliseconds, or 18.2 times a second, which is the standard software
time resolution of the PC. The 8253 count can be read by accessing
the appropriate IO port, and by reading the 8253 count along with the
low word DOS time of day count, we can construct a high resolution
time stamp, which is the base unit of time for TPHRT. The only
modifications we make to the PC environment is to change the mode of
channel 0 to give the output count a 50 percent duty cycle, which does
not impact any other PC operations. Thus we have a simple,
unobtrusive, highly accurate time reference with 838 nanosecond
resolution. Once a highly accurate time reference is available, we
can use it to calibrate a simple function that contains an inner and
outer loop to generate precision delays.
The accuracy of TPHRT is as accurate as the 8253 timer chip and the
ability of the software to measure the overhead in retrieving the 8253
and DOS time of day data. With the advent of advanced chips in the
80286 and 80386 class, the effects of instruction prefetch queues,
pipelining, and cache memory become significant and the same sequence
of instructions may take different amounts of time to execute
depending on the interaction of the processor's performance
optimization mechanisms. The end result is twofold: TPHRT's
calibration routines may experience inaccuracies, and software under
test may give different timing results on different runs. Normally
the "jitter" introduced by these conditions is on the order of a few
microseconds.
A major source of apparent erratic timer behavior comes from the
interaction of asynchronous software and hardware interrupts that may
occur during a timed interval. While the PC/MSDOS environment is
essentially single-threaded, there is enough "background" activity
occurring in the form of timer and keyboard interrupts that these
interrupts may occur during an timed interval, and the time these
interrupts take to complete are naturally counted in the timed
interval. For very short duration timing a TPHRT timer mode with
interrupts disabled is available, but that may not be suitable for
longer duration timings, or when concurrent timer activity is
required. Be aware that few results in the PC environment will be
exactly repeatable, and that some variance in the timing results is
unavoidable.
The high resolution delay function of TPHRT is particularly affected
by background interrupts and processor performance optimization
mechanisms. The initial delay calibration will yield delays with a
variance of from one to three percent of the requested delay interval.
TPHRT 3
Additional functions are available to optimize the delay calibration
to a specific delay interval, and using these functions can reduce the
delay error to between zero and one percent, and thus they are
recommended for critical applications.
TPHRT Function Descriptions
The following is a brief synopsis of the functions found in TPHRT.
This chapter is meant to give the user a brief overview, and is not
meant to be a definitive reference. It is essential that the user
review the complete function reference in the Function Reference
chapter before using any TPHRT function. Some functions may not work
as they would appear at first inspection, and in order to achieve high
performance, TPHRT has a minimum of internal error checking to prevent
such catastrophes as NULL pointer references.
TPHRT Timer Logic
Initialization functions
t_request Requests the number of timers needed.
t_start Initializes the TPHRT timer logic.
t_stop Shuts down TPHRT and frees allocated memory.
Internal functions
t_get Gets TPHRT time stamp with interrupts
enabled.
t_hires_entry Gets TPHRT time stamp with interrupts
disabled. 8253 count is reset.
t_hires_exit Gets TPHRT time stamp and restores interrupts
t_diff Calculates elapsed time difference between
two TPHRT time stamps.
t_calib Calibrates TPHRT timer logic, resets all
timers, and calls the delay calibration
function.
t_bios_entry Receives timer start request from interrupt
service routine.
t_bios_exit Receives timer stop request from interrupt
service routine.
t_bios_load_desc Loads interrupt function description file
t_hook_int Installs timer calls in specified interrupt
vector.
t_unhook_int Removes timer calls from specified interrupt
vector.
t_delay_calib Calibrates delay logic.
t_request is called by the user to specify the number of timers needed
for generic timer operations if the user wishes to override the
default number of timers provided (10). Since each timer data
structure is allocated dynamically, the number of timers available is
restricted by the amount of heap available and the constraints of the
memory model you are using. If t_request is used in your program, it
must be called before t_start.
TPHRT 4
t_start allocates the appropriate amount of heap for the number of
timers requested, initializes those timers, and calibrates the low
level timer routines. t_start must always be invoked prior to using
any other timer functions with the exception of t_request.
t_stop deallocates all allocated heap associated with generic timer
activity and shuts down the timer logic. t_stop must be called prior
to program termination, and no further calls to TPHRT should be made
unless t_start is invoked first.
The TPHRT internal functions of primary interest to the programmer are
t_get, which is the interface to the 8253 timer chip; t_diff, which
calculates the elapsed time between two TPHRT time stamps; and
t_calib, which calibrates the timer and delay logic to the host run-
time environment.
Generic TPHRT Timer Functions
This class of functions implement general purpose timer functionality.
t_entry Starts the specified timer.
t_exit Stops the specified timer.
t_suspend Suspends the specified timer.
t_resume Resumes the specified suspended timer.
t_setmode Specifies timer mode - interrupts on or off.
t_ask_timer Gets accumulated activations and elapsed time
for the specified timer
t_cvt_time Converts microseconds to MM:SS.xxxxxx string.
t_reset Resets one or all timers.
t_report Generates timer report
t_name Associates string with specified timer for
display in timer report.
t_rname Specifies title of timer report.
t_fname Specifies destination file for timer report.
t_set_report Specifies type of timer report generated.
t_entry and t_exit provide the mechanism to start and stop a
microsecond timer. Timers are specified by number from 0 to n-1 in C,
and 1 to n in Pascal. The number of timers available is 10 by
default, but the user can use t_request to request as many timers as
available heap allows. Multiple timers may be active at the same time
if interrupts are enabled.
t_suspend and t_resume suspend and resume a timer previously activated
by t_entry. Timer activation count is not incremented when t_resume
is called, which is useful if you are using timer activation counts to
track subroutine activations in a profiling application, and for some
reason you wish to pause the timer during the subroutine's activation
(perhaps before a call to another routine) and then restart it.
t_setmode allows the user to specify whether timers operate with
interrupts enabled or disabled. With interrupts enabled, intervals
greater than 54925 microseconds may be timed, and multiple timers may
be active concurrently. With interrupts disabled, the timer logic
will "roll over" after 54925 usecs, and only one timer may be active
at any time. Timing short duration events with interrupts disabled is
TPHRT 5
useful if background system interrupts are causing significant
variations in timer results.
t_ask_timer will return to the user the activation count and total
elapsed time in microseconds for the specified timer. t_cvt_time will
convert a microsecond time count into a printable string with the
format MM:SS.xxxxxx. Timer activation counts and accumulated elapsed
time can be reset to zero by using t_reset.
t_report generates a complete listing of all timer activity. This
listing can be directed to the display, a disk file, or a printer.
t_rname allows the user to give the timer report a descriptive title.
t_fname overrides the default disk file name for timer reports going
to disk. t_name allows the user to assign a descriptive text string
to a timer number - this string will be printed next to the timer
number in the timer report. Finally, t_set_report determines what
timers are listed on the timer report: either only those timers that
had been activated, or all timers, regardless of their activation
count, up to the highest timer number activated.
BIOS Interrupt Timer Functions
This class of functions implement the BIOS interrupt timer
functionality.
t_bios_start Installs timers in specified interrupt
vectors.
t_bios_stop Removes all timers from interrupt vectors.
t_bios_suspend Suspends specified interrupt timing.
t_bios_resume Resumes interrupt timing in the specified
vectors.
t_bios_set_user Assigns timer to user specified interrupt.
t_bios_set_file Assigns interrupt function description file
name to the user specified interrupt timer.
t_bios_ask Returns activations and elapsed for the
specified interrupt function
t_bios_reset Resets one or all function timers of the
specified interrupt vector.
t_bios_report Generates BIOS interrupt timer report.
t_bios_rname Specifies title of BIOS timer report.
t_bios_fname Specifies destination file for BIOS timer
report.
t_bios_start initializes BIOS interrupt timing for the interrupts
specified. Heap is allocated for the required data structures,
interrupt function description files are loaded if available, and a
new interrupt service routine for each interrupt to be timed is
inserted in the interrupt vector table. t_bios_stop essentially
reverses this process, freeing allocated heap and restoring the
previous interrupt service vectors. The BIOS timer data structures
are separate from the generic timer structures, and thus t_request has
no effect on BIOS interrupt timer activity.
t_bios_suspend and t_bios_resume allow the user to suspend and resume
BIOS interrupt timing of the specified interrupt(s). All interrupts
to be timed must be installed by t_bios_start, but timing can then be
immediately suspended by t_bios_suspend until the point in the program
TPHRT 6
that the user actually wants timing to begin, when it can be resumed
with t_bios_resume.
t_bios_set_user enables the user to specify an interrupt to be timed
that has not been provided for by TPHRT. Each interrupt that is timed
requires new interrupt service routine that when activated, starts a
timer, calls the old vector, then stops the appropriate timer. TPHRT
provides new timer ISRs for the major device, EMS, Mouse, and MSDOS
interrupts, along with a spare ISR that can be used for any other
interrupt the user might want to time. t_bios_set_user assigns this
spare timer ISR to the specified interrupt, allowing the user to time
any interrupt vector in the PC environment. If the interrupt is a
software interrupt that has specific functions (as requested by the AH
register when the interrupt is invoked) the user may specify an
interrupt function description file using t_bios_set_file which loads
a text file containing interrupt function descriptions if that file is
in the current directory. Interrupt function description files are
provided for all the software interrupts TPHRT has standard timer ISRs
for.
t_bios_ask and t_bios_reset function like their generic timer
counterparts and allow the user to request specific BIOS timer results
or to reset those results to zero.
t_bios_report, t_bios_rname, and t_bios_fname modify and generate the
BIOS timer report in the same way as their generic timer counterparts
t_report, t_rname, and t_fname generate and modify the generic timer
report.
Be sure and carefully review the documentation for t_bios_start before
using the BIOS interrupt timing functions.
Delay Functions
This class of functions implement the microsecond resolution delay
functionality.
t_ask_delay Requests parameters for requested delay time.
t_do_delay Executes delay with interrupts disabled.
t_do_delay_wints Executes delay with interrupts enabled.
t_calc_delay_ff Optimizes delay calibration to a specified
delay duration.
t_get_delay_ff Returns delay calibration optimization.
t_set_delay_ff Sets current delay calibration optimization.
t_min_delay Returns minimum delay possible with current
hardware.
t_res_delay Returns delay resolution possible with
current hardware
t_ask_delay requests delay parameters for the specified delay
interval. These parameters are stored in a user allocated TPHRT
defined data structure and are passed to either t_do_delay, which
generates the delay with interrupts disabled, or t_do_delay_wints,
which generates the delay with interrupts enabled.
t_calc_delay_ff, t_set_delay_ff, and t_get_delay_ff, allows the user
to have the TPHRT delay logic "fine tune" its calibration to a
TPHRT 7
particular delay interval. t_calc_delay_ff calculates and installs
the new delay calibration optimization, t_set_delay_ff enables the
user to install a previously calculated optimization, and
t_get_delay_ff retrieves the current delay optimization.
t_min_delay returns the minimum delay possible in the host run-time
environment. t_res_delay returns the resolution of the delay function
in the host run-time environment.
Examples
While the accompanying pages spell out the functions of TPHRT in
detail, as the saying goes, "a picture is worth a thousand words". In
keeping with that philosophy, we have included several source files
that demonstrate different areas of TPHRT functionality. They are as
follows:
DEMO Basic TPHRT operation. Shows inline and subroutine
timing, report generation.
TESTBIOS BIOS interrupt timing.
SEEKTEST Hard disk seek test benchmark. Uses both inline
timers and BIOS interrupt timing to fully test disk
seek performance.
DELAY Demonstration of high resolution delay functionality.
WATCH Full function Taylor Split stopwatch. Shows how to
activate timers with a user written interrupt service
routine.
These programs are carefully commented and provide valuable insights
into effective TPHRT operation.
Technical Support
Technical support for licensed users of TPHRT is available by the
following methods:
1. By US Mail directed to P.O. Box 22, Mt. Pleasant MI 48804.
2. By Compuserve electronic (Easyplex) mail directed to
73047,1765.
Shareware
This software is distributed as "Shareware", which allows you to use
the complete product on an evaluation basis to get a feel for its
quality, functionality, and value to you as a developer or end user.
At the end of your evaluation (14 days is a widely accepted time for
TPHRT 8
the evaluation period) you may continue to use the software product by
sending in a registration fee to the program author/vendor, or you
must discontinue use of the software and are free to pass your copy on
to another user for evaluation. The Shareware concept allows quality
software to be distributed at far less cost than traditional
commercial products, and allows the user to "try before you buy".
TPHRT is a single language functional subset of PCHRT, the PC Timer
Toolbox distributed through traditional commercial channels by Ryle
Design. MSCHRT for Microsoft C and TCHRT for Turbo C are also
available as Shareware, and provide the same suite of functions as
TPHRT.
Registration of TPHRT costs $20.00, and in return users receive units
for TP 5 & 5.5 (without the shareware messages), complete library
source code, and technical support by US Mail and Compuserv Email.
Distribution of TPHRT object code in commercial applications is not
permitted.
Users developing commerical applications or needing additional timer
functionality should purchase PCHRT, the commerical version of TPHRT,
which costs $49.95. PCHRT includes all the functions of TPHRT, along
with three new timer functions, five new synchronous alarm functions,
four functions to run the timer tick interrupt at a user defined rate,
and two utilities to time execution and profile interrupts of most
executable programs without recompilation. PCHRT comes with libraries
for Turbo C and MSC in small, medium, compact, and large models, as
well as units for Turbo Pascal V5 and V5.5. Full library source code
for both Pascal and C is provided, along with a printed manual and
telephone technical support. Distribution of PCHRT object code in
commercial applications is permitted without royalties.
An order form for these products appears as the last page of this
document.
TPHRT 9
TPHRT 10
TPHRT Function Reference
t_ask_delay
Purpose Fills delay parameter structure with required values
for requested delay interval
Pascal procedure t_ask_delay(usec : longint; var dp :
tdelay_type)
Synopsis Parameters accepted by the delay functions are stored
in a TPHRT defined, user allocated data structure
tdelay_type. t_ask_delay accepts the desired delay
interval in microseconds, and fills the passed
tdelay_type structure with the appropriate parameters
to generate the requested delay. This data structure
is then passed to either t_do_delay or
t_do_delay_wints, where the actual delay is
generated.
Caveat None
See Also t_do_delay, t_do_delay_wints
t_ask_timer
Purpose Returns activation and elapsed time count for a
specified timer
Pascal procedure t_ask_timer(tnum : integer; var hits
:longint; var elapsed : longint)
Synopsis The user may retrieve activation counts and elapsed
time (in 2microseconds) for the specified timer.
Timers are specified from 0 to n-1 in C and from 1 to
n in Pascal. The number of timers n defaults to 10,
but t_request may be called prior to t_start to
increase that number.
Caveat No range checking is done. A NULL pointer reference
is possible if information on a non-existant timer is
requested.
See Also t_request, t_reset
TPHRT 11
t_bios_ask
Purpose Returns activation count and elapsed time for one or
all functions associated with a BIOS interrupt timer
Pascal procedure t_bios_ask(whichint : integer; whichfunc :
integer; var hits : longint; var elapsed : longint)
Synopsis The users passes a single BIOS timer interrupt mask
(see t_bios_start) and either an interrupt function
in the range of 0 to 255 or -1, which causes all the
interrupt function timers to be summed. The
accumulated number of activations and elapsed time in
microseconds is returned.
The summation of all function timers by passing -1
feature is useful if a hardware interrupt that does
not have specific function classes is being timed.
Interrupt functions are specified by the contents of
the AH register, and since the AH register may
contain random, non-specific values when a hardware
interrupt is invoked, many timers for the interrupt
will show some activity. These must be summed in
order to determine the activity of the hardware
interrupt.
Caveat No range checking is done. A NULL pointer reference
is possible if information is requested on an non-
existant interrupt timer.
See Also t_bios_start, t_bios_reset
t_bios_entry
Purpose Receives timer start requests from an interrupt
service routine
Pascal procedure t_bios_entry(whichint : integer; whichfunc
: integer)
Synopsis BIOS interrupt vectors being timed call this routine
to start the appropriate timer for this interrupt.
Parameter whichfunc is the value in the AH register
when the interrupt was invoked, which is the
interrupt function requested in a software interrupt.
Caveat This is an internal TPHRT procedure and is not meant
to be called by the user.
See Also t_bios_exit
TPHRT 12
t_bios_exit
Purpose Receives interrupt timer stop requests from an
interrupt service routine
Pascal procedure t_bios_exit(whichint : integer)
Synopsis BIOS interrupt vectors call this routine to stop the
appropriate timer for this interrupt. The current
active function timer for this interrupt is stopped,
and if the interrupt was entered recursively, the
previous function timer is restarted.
Caveat This is an internal TPHRT procedure and is not meant
to be called by the user.
See Also t_bios_entry
t_bios_fname
Purpose Specifies a name for the disk file created by the
BIOS timer report if the disk destination option is
selected
Pascal procedure t_bios_fname(fname : string)
Synopsis By calling t_bios_report(1) the BIOS timer report is
generated and sent to an ASCII disk file. The
default name for this file is BIOSTIME.TXT.
t_bios_fname allows the user to specify a different
filename, with complete disk, path, and file
specification.
Caveat Maximum disk/path/filename string length is 67
characters
See Also t_bios_report
t_bios_load_desc
Purpose Loads an interrupt description file into the
appropriate interrupt timer data structure
Pascal procedure t_bios_load_desc(whichint : integer; fname
: string)
Synopsis Each interrupt vector being timed contains 256
timers, one for each possible interrupt function as
indicated by the AH register. An interrupt
description file contains brief twenty character
descriptions of each interrupt function, and if
loaded, these will appear along with the interrupt
TPHRT 13
function number in the BIOS interrupt timer report.
whichint is a BIOS timer interrupt mask (see
t_bios_start), and data_file is the disk/path/file
descriptor. No error is generated if the specified
file is not found.
See one of the supplied interrupt description files
(such as 10.INT) for the layout of these files.
This routine is called automatically by t_bios_start.
Caveat No range checking is done. NULL pointer reference is
possible.
See Also t_bios_start, t_bios_set_file
t_bios_report
Purpose Generates BIOS interrupt timer report
Pascal procedure t_bios_report(integer : whereto)
Synopsis This routine generates a complete timer report for
all active BIOS interrupt timers. whereto specifies
the report's destination - 0 sends the report to the
display, 1 to a disk file, and 2 to a printer.
Caveat None.
See Also t_bios_rname, t_bios_fname
t_bios_resume
Purpose Resumes suspended BIOS interrupt timing
Pascal procedure t_bios_resume(biosmask : integer)
Synopsis This routine enables previously suspended BIOS
interrupt timing. biosmask contains the BIOS timer
bitmask (see t_bios_start) of the interrupts to have
timing re-enabled.
Caveat No range checking is done. NULL pointer reference is
possible if a interrupt is referenced that was not
setup by t_bios_start.
See Also t_bios_suspend, t_bios_start
TPHRT 14
t_bios_reset
Purpose Resets one or all timers associated with a timed
interrupt
Pascal procedure t_bios_reset(whichint : integer; whichfunc
: integer)
Synopsis This function allows the user to reset either one
specific or all function timers associated with a
timed interrupt. Specific function timers are in the
range of 0 to 255. Passing -1 for whichfunc resets
all 256 timers associated with a timed interrupt.
The interrupt is specified by whichint which is a
single BIOS interrupt timer mask (see t_bios_start).
Caveat No range checking is done. NULL pointer reference is
possible if a non-existant interrupt timer is
specified.
See Also t_bios_start, t_bios_ask
t_bios_rname
Purpose Specifies title for BIOS timer report
Pascal procedure t_bios_rname(rname : string)
Synopsis This function allows the user to specify a title for
the BIOS interrupt timer report. If none is
specified, the title used is Bios Interrupt Timer
Summary. The title is horizontally centered.
Caveat Max string length is 80 characters.
See Also t_bios_report, t_bios_fname
t_bios_set_file
Purpose Sets the interrupt function description file for the
user specified interrupt timer
Pascal procedure t_bios_set_file(ufile : string)
Synopsis When a user specifies the optional interrupt to time
using t_bios_set_user, a file of interrupt function
descriptions may also be specified using this
function.
Caveat Max file description length is 67 characters.
See Also t_bios_load_desc, t_bios_set_file
TPHRT 15
t_bios_set_user
Purpose Specifies the optional interrupt to time
Pascal procedure t_bios_set_user(user_int : integer)
Synopsis The TPHRT BIOS timing functionality has built in
support for the various BIOS interrupts of interest -
disk, CRT, serial, parallel, DOS, EMS, keyboard, and
mouse. This function allows the user to specify any
other interrupt to be timed, and when t_bios_start is
invoked with the USER bit set in the timer bitmask,
the interrupt specified by t_bios_set_user will have
timers inserted in its vector.
Caveat The ISR supplied that is hooked into the user
specified interrupt (t_new_user in the .ASM modules)
does not propagate the FLAGS register. If you are
attempting to time a software interrupt that returns
meaningful information in the FLAGS register, you
should modify the t_new_user routine so that it's
last instruction is a RETF 2 instead of IRET. This
is documented in the t_new_user code.
See Also t_bios_start, t_bios_set_file
t_bios_start
Purpose Initializes BIOS interrupt timing
Pascal procedure t_bios_start(biosmask : integer)
Synopsis This function initializes BIOS interrupt timing. The
interrupts to be timed are selected by passing the
appropriate bitmask:
CRT10 INT 10h Video Services
DISK INT 13h Disk Services
COM INT 14h Serial Port Services
KEYBD INT 16h Keyboard Services
PRT INT 17h Printer Services
DOS21 INT 21h MSDOS System Services
MOUSE INT 33h Mouse Services
EMS INT 67h EMS Services
USER User Specified Interrupt
TPHRT 16
As an example, to insert timers in the DOS interrupt
and the disk interrupt, one would invoke
t_bios_start(DISK+DOS21).
Each interrupt timed actually has 256 individual
timers, one for each possible value in the AH
register, which indicates what specific function of
that interrupt has been requested. The timer data
structure is allocated dynamically, and each
structure requires approximately 9200 bytes, so there
is a limit imposed by the memory model being used as
to how many interrupt timers may be requested.
t_bios_start returns FALSE in C if the amount of
memory needed is not available, while a run-time
error occurs in Turbo Pascal.
If the USER bitmask is to be used, t_bios_set_user
must be invoked prior to t_bios_start to indicate
what interrupt the USER bitmask will time.
Interrupt function description files for the
supported interrupts are supplied, and will be loaded
if they are present in the run-time directory. As
these will dramatically improve the information
presented in the BIOS interrupt timer report, they
are recommended. t_bios_set_file associates a file
with the USER selected interrupt.
If testing code with BIOS interrupt timing active,
and the code fails prior to calling t_bios_stop, then
you should immediately reboot your computer, as the
interrupt vectors being timed are pointing to non-
existant code.
Caveat Approximately 9200 bytes are required for each
interrupt to be timed. Memory constraints can affect
this function.
See Also t_bios_stop, t_bios_set_user, t_bios_set_file,
t_bios_suspend, t_bios_resume
t_bios_stop
Purpose Stops all BIOS interrupt timing
Pascal procedure t_bios_stop;
Synopsis This function removes all timers from all interrupt
vectors selected by t_bios_start and deallocates all
memory associated with those timers.
Caveat This function must be called prior to program exit in
order to restore the interrupt environment. If the
code under test fails prior to t_bios_start the
TPHRT 17
interrupt vectors being timed will be pointing to
non-existant code, and a system hang is likely.
See Also t_bios_start, t_bios_suspend, t_bios_resume
t_bios_suspend
Purpose Suspends interrupt timing selected by t_bios_start
Pascal procedure t_bios_suspend(biosmask : integer)
Synopsis BIOS interrupt timing is initiated by t_bios_start,
and terminated by t_bios_stop. t_bios_suspend gives
the user the ability to selectively disable timing on
a particular interrupt or interrupts by passing an
appropriate biosmask (see t_bios_start). This
suspended interrupt timing may be later resumed by
invoking t_bios_resume.
Caveat No range checking is done. NULL pointer reference is
possible if a non-existant interrupt timer is
referenced.
See Also t_bios_resume, t_bios_start, t_bios_stop
t_calc_delay_ff
Purpose Optimizes delay calibration for a specific delay
interval
Pascal function t_calc_delay_ff(delay_time : longint;
ints_or_not : integer)
Synopsis This function optimizes delay calibration to a
specific delay interval. ints_or_not can be either
INTS_ON, indicating a delay with interrupts enabled
should be used for the optimization calculation, or
NO_INTS_ON, which indicates that a delay with
interrupts disabled should be used. This function
sets a global value that is used by t_ask_delay, and
the value is also returned, so that it may be stored
for later use with the delay interval optimized.
Caveat None
See Also t_set_delay_ff, t_get_delay_ff, t_ask_delay
t_calib
Purpose Calibrates the TPHRT timer and delay logic
TPHRT 18
Pascal procedure t_calib
Synopsis This function calibrates the low level TPHRT timer
and delay logic. It is called by t_start, so the
user need not explicitly call this routine unless
additional delay calibration is needed after a system
parameter has been modified during a timing run - a
keyboard initiated system clock speed change is an
example. t_calib calls t_delay_calib to calibrate
the TPHRT delay logic.
Caveat None
See Also t_delay_calib
t_cvt_time
Purpose Converts a microsecond count to a MM:SS.xxxxxx format
string
Pascal function t_cvt_time(usec : longint; tstring : string)
: string
Synopsis This function accepts a microsecond count and returns
a printable character string in a simple time format.
This function is useful to the user who wishes to
build custom timer reports.
Caveat Destination string length should be 13 characters.
See Also t_ask_timer, t_bios_ask
t_delay_calib
Purpose Calibrates the TPHRT delay logic
Pascal procedure t_delay_calib
Synopsis This function calibrates the delay loops used to
generate precision microsecond delays. Additional
calibration is available from t_calc_delay_ff.
t_delay_calib is called by t_calib, so the user need
not call it explicitly.
Caveat None
See Also t_calib, t_calc_delay_ff
TPHRT 19
t_diff
Purpose Calculates the difference between two TPHRT time
stamps
Pascal function t_diff(start, stop : TPHRT_type) : longint
Synopsis This function returns the difference in microseconds
between two TPHRT time stamps, which are generated by
calls to t_get. t_diff and t_get are low level
functions that are of interest primarily to users
building timer functions not implemented in TPHRT.
Caveat Don't pass the time stamps in the wrong order.
See Also t_get
t_do_delay
Purpose Generates a precision microsecond delay with
interrupts disabled
Pascal procedure t_do_delay(dp : tdelay_type)
Synopsis This function generates a precision microsecond delay
with interrupts disabled. Using this function for
delays greater than 54925 microseconds will cause the
PC clock to lose time. Delay parameters of type
tdelay_type for the delay interval desired are
generated by t_ask_delay.
Delay interval error will be in the range of one to
three percent if t_calc_delay_ff is not used, zero to
one percent if it is.
Caveat Interrupts are disabled during the delay period
See Also t_ask_delay, t_calc_delay_ff, t_do_delay_wints
t_do_delay_wints
Purpose Generates a precision microsecond delay with
interrupts enabled
Pascal procedure t_do_delay_wints(dp : tdelay_type)
Synopsis This function is identical to t_do_delay except that
interrupts are enabled during the delay interval.
This will introduce some additional error in the
delay produced, but is more appropriate for longer (
> 54925 usec) delays. Delay parameters of type
TPHRT 20
tdelay_type for the delay interval desired are
generated by t_ask_delay.
Delay interval error will be in the range of one to
three percent if t_calc_delay_ff is not used, zero to
one percent if it is.
Caveat Interrupt activity may cause random errors in the
delay interval produced.
See Also t_do_delay, t_ask_delay, t_calc_delay_ff
t_entry
Purpose Starts the specified general purpose timer
Pascal procedure t_entry(timernum : integer)
Synopsis This function starts a general purpose timer
counting. Timers are specified from 0 to n-1 in C,
and from 1 to n in Pascal. The default number of
timers is 10, but that can be modified prior to
calling t_start by passing the number of timers
needed to t_request.
Interrupts are normally enabled during a timing
interval. t_setmode can be used to disable
interrupts during any or all timing intervals.
Caveat No range checking is done. NULL pointer reference
possible if non-existant timer is started.
See Also t_exit, t_setmode
t_exit
Purpose Stops the specified general purpose timer
Pascal procedure t_exit(timernum : integer)
Synopsis This function stops a general purpose timer counting.
Activation count and accumulated elapsed time for the
specified timer is updated. Timers are specified
from 0 to n-1 in C, and from 1 to n in Pascal. The
default number of timers is 10, but that can be
modified prior to calling t_start by passing the
number of timers needed to t_request.
Caveat No range checking is done. NULL pointer reference
possible if non-existant timer is started.
See Also t_entry
TPHRT 21
t_fname
Purpose Changes name of timer report file
Pascal procedure t_fname(fname : string)
Synopsis t_report can send its output to a disk file, which
has the default name TIMER.TXT. This function allows
the user to assign a different disk/path/file name to
this file.
Caveat No checking is done to determine if the file
description is valid. Maximum string length is 67
characters.
See Also t_rname, t_report
t_get
Purpose Retrieves a high resolution time stamp with
interrupts enabled
Pascal procedure t_get(var timestamp : TPHRT_type)
Synopsis This function interrogates the 8253 timer chip and
the low 16 bits of the DOS time of day data words
fills the passed TPHRT_type data structure with the
microsecond resolution timestamp. This is the
fundamental unit of time for TPHRT. The elapsed time
between two TPHRT_type time stamps may be determined
by t_diff.
Caveat Interrupts are enabled when t_get returns.
See Also t_hires_entry, t_hires_exit
t_get_delay_ff
Purpose Retrieves the current delay calibration optimization
Pascal function t_get_delay_ff : real
Synopsis t_calc_delay_ff calculates and installs a delay
calibration optimization for a specified delay
interval length. Using this additional optimization
can vastly improve the TPHRT delay accuracy in
critical applications. t_get_delay_ff returns the
current delay calibration optimization in effect.
The default value (i.e. - no additional optimization)
is 1.00.
Caveat None
TPHRT 22
See Also t_calc_delay_ff, t_set_delay_ff
t_hires_entry
Purpose Initiates timing with interrupts disabled
Pascal procedure t_hires_entry(var timestamp : TPHRT_type)
Synopsis This function, like t_get, retrieves a TPHRT
timestamp from the timing hardware. Unlike t_get,
t_hires_entry resets the 8253 timer chip to 0, and
interrupts are disabled at exit. This facilitates a
timing mode (set by t_setmode) that functions with
interrupts disabled.
Caveat Since the 8253 is reset, only one timer may be active
at any one time. The timer will "roll over" after
54925 usec, so this mode is suitable for short
duration timing only. This is a low level function,
and is not meant to be called by the user.
See Also t_hires_exit, t_setmode
t_hires_exit
Purpose Concludes a timing interval with interrupts disabled
Pascal procedure t_hires_exit(var timestamp : TPHRT_type)
Synopsis This is the companion function to t_hires_entry and
completes a timing interval with interrupts disabled.
At exit interrupts are enabled.
Caveat See t_hires_entry.
See Also t_hires_entry, t_setmode
t_hook_int
Purpose Installs timers in the specified interrupt vector
Pascal procedure t_hook_int(int_no : integer)
Synopsis This function installs timers in the specified
interrupt vector to enable precise timing of the
interrupt activity.
Caveat This is a low level function and is not meant to be
called by the user. Users wishing to understand how
TPHRT interrupt timing is accomplished should inspect
the source code to this routine.
TPHRT 23
See Also t_unhook_int
t_min_delay
Purpose Returns minimum delay possible in run-time
environment
Pascal function t_min_delay : longint
Synopsis The minimum delay interval that can be generated by
t_do_delay or t_do_delay_wints varies with the run-
time hardware environment. This function returns the
minimum delay in microseconds that can be generated
in the current environment.
Caveat None
See Also t_res_delay
t_name
Purpose Associates a descriptive string with a generic timer
Pascal procedure t_name(timerno : integer; timername :
tname)
Synopsis This functions assigns a string of maximum 20
characters to the specified generic timer number, and
this string is then displayed next to the timer
number in the timer report generated by t_report.
Caveat Maximum string length is 20 characters.
See Also None
t_report
Purpose Generates a report of all generic timer activity
Pascal procedure t_report(whereto : integer)
Synopsis This function generates a report of all timer
activity that was generated using t_entry and t_exit.
Parameter whereto specifies the report's destination:
0 sends the report to the CRT display, 1 sends it to
a disk file, and 2 sends it to the printer. The
report may have a title (see t_rname), and the
destination disk file (if used) defaults to
TIMER.TXT, but this can modified (see t_fname).
TPHRT 24
Timer reports have two formats, and these are
selected by t_set_report. The HIGHWATER report type
shows the activity of all timers, including those
with zero activation counts, up to the highest number
timer activated. The NONZERO report type only shows
timers with nonzero activation counts.
Caveat None
See Also t_rname, t_fname, t_set_report
t_request
Purpose Request specific number of generic timers
Pascal procedure t_request(numtimer : integer)
Synopsis t_request provides a mechanism to override the
default number of generic timers allocated by
t_start. If the user requires more (or less) than 10
timers, the number required may be passed to
t_request, and t_start will attempt to allocate this
number of timers.
Caveat Call before t_start.
See Also t_start
t_res_delay
Purpose Retrieves delay resolution of run-time environment
Pascal function t_res_delay : longint
Synopsis In slower hardware environments, the delay resolution
of t_do_delay and t_do_delay_wints may be several
microseconds. This function returns the run-time
delay resolution in units of tenths of a microsecond.
For example, if t_res_delay returns a value of 44,
that means the delay functions can generate delays
starting at their minimum delay length (see
t_min_delay) and up in increments of 4.4
microseconds.
Caveat None
See Also t_min_delay
t_reset
Purpose Resets one or all generic timers
TPHRT 25
Pascal procedure t_reset(timernum : integer)
Synopsis This function zeros the accumulated activation and
elapsed timer counts for a specified timer in the
range of 0 to n-1 in C, or 1 to n in Pascal. If -1
is passed, all generic timers are reset.
Caveat No range checking is done. Null pointer reference is
possible if a non-existant timer is specified.
See Also t_ask_timer
t_resume
Purpose Resumes a suspended generic timer
Pascal procedure t_resume(tnum : integer)
Synopsis Functions t_suspend and t_resume allow the user to
stop and restart an active timer without incrementing
its activation count.
Caveat No range checking is done. NULL pointer reference is
possible if a non-existant timer is specified.
See Also t_suspend
t_rname
Purpose Assigns a title to the timer report
Pascal procedure t_rname(report_title : string)
Synopsis The generic timer report generated by t_report
contains a horizontally centered title, which
defaults to Timer Summary. This function allows the
user to specify an alternate title.
Caveat Max string length is 80 characters.
See Also t_report, t_fname
t_set_delay_ff
Purpose Sets delay calibration optimization
Pascal procedure t_set_delay_ff(delay_ff : real)
Synopsis This function allows the user to set the new delay
calibration optimization for use by t_ask_delay.
Delay calibration optimization for a given delay
TPHRT 26
interval can be automatically calculated and set by
t_calc_delay_ff. Calling t_set_delay_ff with a value
of 1.00 removes any delay calibration optimization
that was in effect.
Caveat None
See Also t_calc_delay_ff, t_get_delay_ff, t_ask_delay
t_setmode
Purpose Sets generic timing mode
Pascal procedure t_setmode(modetype : integer)
Synopsis Two modes of generic timing are available: INTS_ON
enables generic timing using t_entry and t_exit with
interrupts enabled, and this is the default mode.
NO_INTS_ON enables timing with interrupts disabled,
and this mode is particularly suitable for extremely
short duration timing that may be skewed by
background interrupt activity. In this mode, only
one timer may be active at any time, and each timer
will "roll over" after 54925 microseconds of
continuous activation.
As long as only one timer is active at once, the two
timer modes may be freely mixed. In order to change
modes, call t_setmode with the desired mode prior to
calling the t_entry/t_exit functions.
Caveat NO_INTS_ON mode is not compatible with multiple
active timers or BIOS interrupt timing.
See Also None
t_start
Purpose Initializes TPHRT timing functions
Pascal procedure t_start
Synopsis This function initializes the entire TPHRT timing
system, and must be called prior to any other TPHRT
functions with the exception of t_request. If a
different number of timers other than the default
number provided (10) is required, t_request should be
called prior to t_start to specify the number needed.
In C, if t_start can allocate enough heap to fulfill
the timer request, it will do so, calibrate the
timing system, and return TRUE. If the memory
request fails, it will return FALSE. In Turbo
Pascal, memory allocation failure will result in a
TPHRT 27
run-time error. Each timer requires approximately 35
bytes of heap.
The 8253 timer chip is set to mode 2.
Caveat None
See Also t_request, t_stop
t_stop
Purpose Shuts down TPHRT timing logic
Pascal procedure t_stop
Synopsis This function deallocates all heap associated with
generic timers and restores the 8253 timer chip to
mode 3. It must be called prior to program exit, and
no TPHRT calls (except t_request) are valid without a
call to t_start to reinitialize the timing system.
Caveat None
See Also t_start, t_request
t_suspend
Purpose Suspends an active generic timer
Pascal procedure t_suspend(tnum : integer)
Synopsis Functions t_suspend and t_resume allow the user to
stop and restart an active timer without incrementing
its activation count.
Caveat No range checking is done. NULL pointer reference is
possible if a non-existant timer is specified.
See Also t_resume
t_unhook_int
Purpose Removes timers from the specified interrupt vector
Pascal procedure t_unhook_int(int_no : integer)
Synopsis This function removes timers from the specified
interrupt vector to disable precise timing of the
interrupt activity.
TPHRT 28
Caveat This is a low level function and is not meant to be
called by the user. Users wishing to understand how
TPHRT interrupt timing is accomplished may want to
inspect the source code to this routine.
See Also t_hook_int
TPHRT 29
TPHRT V3.00 Registration
Name ______________________________ Company ______________________________
Address __________________________________________________________________
City/State/Zip ___________________________________________________________
Telephone _______________________ Got TPHRT from _________________________
Version 3 Single Language Timer Toolboxes. Includes large & small
model libraries (C), full library source, support by US Mail or
Compuserve Email. License does not permit commercial distribution
of object code.
Qty _____ TPHRT V3 for Turbo Pascal 5 & 5.5 @ $20.00 each ........ _______
Qty _____ TCHRT V3 for Turbo C @ $20.00 each ..................... _______
Qty _____ MSCHRT V3 for Microsoft C @ $20.00 each ................ _______
Version 4 Timer Toolbox. Supports TC & MSC in small, medium,
compact, and large models, Turbo Pascal 5 & 5.5. 20 additional
functions to manage timers, profile interrupts, generate synchronous
alarms, run the timer tick interrupt at a user specified rate.
Two standalone utilities time execution and profile interrupts of
most executable programs without recompilation. Full library
source in C & Pascal included. Printed manual. Support by
telephone, US Mail or Compuserv Email. License permits
commercial distribution of object code.
Qty ______ PCHRT V4.00 @ $49.95 each ............................. _______
Shipping in USA @ $2.00 .......................................... _______
Shipping outside USA @ $4.00 ..................................... _______
Subtotal ......................................................... _______
Michigan residents add 4% ........................................ _______
Total enclosed ................................................... _______
Payment method: ___Check ___Money Order ___VISA ___MasterCard
Card # ____________________________________________ Exp _________
Signature _________________________________________
Remit to Ryle Design, P.O. Box 22, Mt. Pleasant, MI 48804
Credit card customers may order by Email on Compuserve to
73047,1765, or by telephone at (517) 773-0587. This is a voice
mail system. Leave your name and number in voice mailbox #2, and
your call will be returned and your order taken.
Thank you!
TPHRT 30
